<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SWIG and R</title>
<link rel="stylesheet" type="text/css" href="style.css">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>

<body bgcolor="#ffffff">
<H1><a name="R">37 SWIG and R</a></H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#R_nn2">Bugs</a>
<li><a href="#R_nn3">Using R and SWIG</a>
<li><a href="#R_nn4">Precompiling large R files</a>
<li><a href="#R_nn5">General policy</a>
<li><a href="#R_language_conventions">Language conventions</a>
<li><a href="#R_nn6">C++ classes</a>
<li><a href="#R_nn7">Enumerations</a>
</ul>
</div>
<!-- INDEX -->



<p>
R is a GPL'ed open source statistical and plotting environment.
Information about R can be found at <a
href="http://www.r-project.org/">www.r-project.org</a>.

The R bindings are under active development.  They have been used to
compile and run an R interface to QuantLib running on Mandriva Linux
with gcc. The R bindings also work on Microsoft Windows using Visual C++.
</p>

<H2><a name="R_nn2">37.1 Bugs</a></H2>


<p>
Currently the following features are not implemented or broken:
</p>

<ul>
<li>Garbage collection of created objects
<li>C Array wrappings
</ul>

<H2><a name="R_nn3">37.2 Using R and SWIG</a></H2>


<p>
To use R and SWIG in C mode, execute the following commands where
example.c is the name of the file with the functions in them
</p>

<div class="shell">
<pre>
swig -r example.i
R CMD SHLIB example_wrap.c example.c
</pre>
</div>

<p>
The corresponding options for C++ mode are
</p>

<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
R CMD SHLIB example_wrap.cpp example.cpp
</pre>
</div>

<p>
Note that R is sensitive to the names of the files.
The name of the wrapper file must be the
name of the library unless you use the -o option to R when building the library, for example:
</p>

<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
R CMD SHLIB -o example.so example_wrap.cpp example.cpp
</pre>
</div>

<p>
R is also sensitive to the name of the file 
extension in C and C++ mode. In C++ mode, the file extension must be .cpp
rather than .cxx for the R compile command to recognize it. If your C++ code is 
in a file using something other than a .cpp extension, then it may still work using PKG_LIBS:
</p>

<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
PKG_LIBS="example.cxx" R CMD SHLIB -o example example_wrap.cpp
</pre>
</div>

<p>
The commands produces two files.  A dynamic shared object file called
example.so, or example.dll, and an R wrapper file called example.R.  To load these
files, start up R and type in the following commands
</p>

<div class="shell">
<pre>
dyn.load(paste("example", .Platform$dynlib.ext, sep=""))
source("example.R")
cacheMetaData(1)
</pre>
</div>

The cacheMetaData(1) will cause R to refresh its object tables.
Without it, inheritance of wrapped objects may fail.

<p>
These two files can be loaded in any order
</p>

<p>
  If you are compiling code yourself (not using R itself), there are a few things to watch out for:
</p>

<ul>
<li>The output shared library name (to the left of the file extension) MUST match the module name, or alternatively, you can also set the -package NAME command line argument.  See swig -r -help for more information
<li>If you do not set the output file name appropriately, you might see errors like 
<div class="shell">
<pre>
> fact(4)
Error in .Call("R_swig_fact", s_arg1, as.logical(.copy), PACKAGE = "example") :
  "R_swig_fact" not available for .Call() for package "example"
</pre>
</div>
<li>Make sure the architecture of the shared library(x64 for instance), matches the architecture of the R program you want to load your shared library into
</ul>

<H2><a name="R_nn4">37.3 Precompiling large R files</a></H2>


In cases where the R file is large, one make save a lot of loading
time by precompiling the R wrapper.  This can be done by creating the
file makeRData.R which contains the following

<pre>
source('BigFile.R')
save(list=ls(all=TRUE),file="BigFile.RData", compress=TRUE)
q(save="no")
</pre>

This will generate a compiled R file called BigFile.RData that
will save a large amount of loading time.



<H2><a name="R_nn5">37.4 General policy</a></H2>


<p>
The general policy of the module is to treat the C/C++ as a basic
wrapping over the underlying functions and rely on the R type system
to provide R syntax.
</p>

<H2><a name="R_language_conventions">37.5 Language conventions</a></H2>


<p>
getitem and setitem use C++ conventions (i.e. zero based indices). [<-
and [ are overloaded to allow for R syntax (one based indices and
slices)
</p>

<H2><a name="R_nn6">37.6 C++ classes</a></H2>


<p>
C++ objects are implemented as external pointer objects with the class
being the mangled name of the class. The C++ classes are encapsulated
as an SEXP with an external pointer type. The class is the mangled
name of the class. The nice thing about R is that is allows you to
keep track of the pointer object which removes the necessity for a lot
of the proxy class baggage you see in other languages.
</p>

<H2><a name="R_nn7">37.7 Enumerations</a></H2>


<p>
enumerations are characters which are then converted back and forth to
ints before calling the C routines. All of the enumeration code is
done in R.
</p>

</body>
</html>
